 _________     ________    _________
/\   _____\   /  ____  \  /\   _____\
\ \  \____/  /\  \   \  \ \ \  \____/
 \ \  \_____ \ \  \   \  \ \ \  \_____
  \ \_____  \ \ \  \   \  \ \ \_____  \
   \/____/\  \ \ \  \   \  \ \/____/\  \
     ____\_\  \ \ \  \___\  \  ____\_\  \
    /\_________\ \ \________/ /\_________\
    \/_________/  \/_______/  \/_________/ v1.2
------->by Joe Wingbermuehle 05-22-1998<-------

>Contents:
 -Contents - This is what you are reading!
 -Beta? - Describes what the purpose of this release is.
 -What is it? - Describes the program and it's features.
 -Read This - Important information about SOS.
 -Installation - The two simple steps to installing SOS.
 -Keys - A quick summary of commonly used keys for SOS.
 -List of Included Programs - Shows what is in sos.83g.
 -My Goal - Describes my goal in making SOS.
 -Misc. User Notes - Notes for "power users."
 -Misc. Programmer Notes - Notes for "power programmers."
 -Detection of Programs - Describes the SOS program format.
 -SOS History - The releases of SOS (for those history scholars).
 -Features to be Added - Features that may appear in future versions.
 -FAQAA - Frequently Asked Questions And Answers.
 -Concluding Comments - A little more information, just read it!

>What is it?
This is an Operating System (or shell... kind of between the two) for
the TI-83 (SOS = Swapping Operating System).
Here is a list of features:
	-Automatically detects asm programs
	-Assembly language programs can run with only 815 bytes	of free ram.
	-Program write back (allowing high scores and other settings
		to be easily saved).
	-User-friendly interface.
	-Supports up to 250+ programs.
	-Allows for contrast changing.
	-A program description is shown for the highlighted program.
	-Shows program size/free memory.
	-Eight programs visible at a time.
	-Supports APD (Auto Power Down).
	-Runs all assembly language AShell programs.
	-Allows for libraries containing commonly used routines.
	-Saves the highlighted program while in SOS.
	-The GUI uses little power (the same as if you were in the TI-OS).

**************>READ THIS!!! **********************************************************
Please do not complain to me without fully reading this file!
Load all external levels and libraries AFTER the programs to which they belong!
 Not doing so will cause the programs to act up and possibly crash!
SOS programs will NOT work with AShell, however, AShell programs WILL work with SOS.
If you see a name under the free memory, then you are missing a library required to
 run the highlighted program. The name is the name of the missing library.
If SOS refusses to start, then you probably don't have any SOS or AShell programs
 loaded in memory (also, you may not have enough memory to run SOS).
DO NOT attempt to run a SOS program outside of SOS!
DO NOT attempt to send/recieve a program to the calculator while running SOS!!!!!
**************************************************************************************

>Installation:
Copy sos.83g to your TI-83.
Run SOS.

>Keys:
To start a program:  [Y=].
To move to a different program:  [(up)] or [(down)].
To move to the next list of programs:  [(right)].
To change the contrast:  (same as on home screen).
To shut down within SOS:  [2nd]+[ON].
To exit SOS:  [GRAPH].
Note that SOS will shut down the calculator after about 6 minutes of no activity.
 Press [ON] to get it back (this will only happen while no programs are running).

>List of included programs:
	A - the program you run (required).
	ZSOS - the compressed SOS program (required).
	ZSOSL - the loader for SOS (required - note that SOS does NOT require ZASMLOAD).
	ZLIB - A library file for SOS (used in Breakout).
	BREAKOUT - A game I wrote, included as an example SOS program.

>My Goal:
The goal of SOS is to be the smallest, easy-to-use shell for the TI-83. I made it to
be useful, not necessarily pretty. With SOS, you can have more programs on your TI-83
than with any other shell (at the time this was written). I have met my goals, but
SOS can probably still be improved so my work continues....

>Misc. User Notes:
 -SOS uses GetKey for detecting keys, therefore, many of the standard TI-83
  features will work from SOS (such as contrast).

>Misc. Programmer Notes:
 -SOS switches to im 1 at startup (and when a program ends) to prevent conflicts.
 -SOS clears both the screen and the graph buffer when a program is started.
 -SOS does not check the first byte of a program so you can use ANY one-byte
  instruction as long as the second instruction is jr.
  * Unless your program uses no libraries, do NOT use nop, as an SOS program will
    crash under AShell (AShell uses nop and checks for it).
 -Library pointers are stored in the command shadow two bytes after the end of the
  loader routine for SOS (the loader is 38 bytes) since each library takes 3 bytes
  on the vector table, you can use the area after your libraries for more variables.
 -It is possible to use more than 16 libraries, look at "SOS.inc" if you would like
  to figure it out.
 -Please include libraries and external levels for an SOS program AFTER the main
  program in a group file. I would recommend ALWAYS using group files.

>Detection of programs:
Since there are many AShell programs already out, I decided to make the
shell "AShell-compatable."  ANY program written for AShell (asm) will work with SOS.
For asm programs, the beginning of the program must look something like this:

	.nolist
	#include	"sos.inc"	; contains the lib/vector definitions
	.list
	.org	$9327	
	;----> This code is required for ALL SOS programs:
	ccf		; make this program SOS compatable
	jr	Program		; jump to the start of the program
	.dw	Libraries-$9327	; pointer to a list of libraries used ($0000 if none used)
	.dw	Description	; pointer to a description (0 terminated)
	;----> end required code

Program:
	call	vector1	; call library ZLIB routine 0
	call	vector0	; call library ZLIB routine 3
	ret

Description:
	.db	"THE Ultimate Game by BOB!",$00
Libraries:
	.db	"ZLIB",0,0,0,0,lib0,vect1	; set up vector 1 to be ZLIB routine 0
	.db	"ZLIB",0,0,0,0,lib3,vect0	; set up vector 0 to be ZLIB routine 3
	.db	$FF		; end of libraries

.end

The library format:
	-First 8 bytes are the library name (use 0s if less than 8 bytes).
	-Library routine (lib0....libF)
	-Vector number (vect0....vectF)
	- [ $FF if end of list, otherwise continue the list...]

*---->All asm programs MUST be compressed!
*---->DO NOT USE THE MEMORY AREA CMDSHADOW!!!!!
	Using the cmdshadow could cause the calc to crash!
	(if you use only the first 13 bytes at the beginning no harm will be done).

>SOS history:
Version 0.5
	-First beta release! Let me know what you find!
Version 1.0 (I'm not documenting non-public releases)
	-No longer supports BASIC programs.
	-Fixed a minor bug.
	-Program size has been greatly reduced.
	-Keys have been changed (see ">Keys").
Version 1.1
	-Fixed a few bugs.
	-[2nd]+[ON] has been disabled.
Version 1.2
	-SOS is much smaller (needs only 815 bytes to run).
	-[2nd]+[ON] now shuts down the calculator.
	-The start program prgmSOS has been renamed to prgmA.
	-I took out the "Description:" label (it was useless).
	-SOS now tells what library is missing rather than "Lib Error!"

>Features to be added:
	-Add-on files for SOS to support more custom settings etc.
	-Will be run by pressing [ALPHA] + [ON].
	-Possible BASIC program support again (maybe an add-on type thing).
	-Let me know!

>FAQAA (pronounced: fahquah - like the color aqua with an "F" sound):
Q - Why is this file (sos.txt) so huge?
A - I took the time to make sure I did not skip over anything to avoid responding to
	the same questions over and over again. While making this file, it helped me
	organize my thoughts and make SOS a better program as well. (Dulce [Dan E]
	told me too make a huge readme, so blame him! :P)
Q - Why did you use [Y=] to start a program?
A - I used [Y=] to start a program because of the large number of programs that use
	[2nd], [ALPHA] etc. on their menu screens. [Y=] is rarely if ever used and,
	while it may be akward at first, I think it is the easiest solution. Another
	reason for this choice is that it allows SOS to be much smaller.
Q - Why did you use [GRAPH] to exit SOS?
A - The biggest reason was to keep SOS similar to AShell. Another reason was to keep
	with the basic theme of using [Y=] to start a program; makes it logical.
Q - What is with the funky name (SOS)?
A - There are a couple of reasons for that selection:
	-It is only three characters (fits with my name at the top of the screen and
		makes the program a little smaller than some other choices).
	-It has a nice, familiar, ring to it.
	-It describes almost perfectly what SOS is (it is an operating system that
		swaps data to allow more programs to be on the TI-83 hence the
		name: "Swapping Operating System" or "SOS")
Q - Will the format for the libraries etc. change?
A - It is not likely that I will change the format unless I find a much better way
	of doing it, however, it is possible.
Q - Will SOS ever have a password program, screen saver, or icons?
A - NO! That is ridiculous!
Q - Will Auto-Power-Down (APD) cause the memory leak to occur?
A - No, only sending/recieving from within SOS.
Q - Will you respond to my email if I ask a question that is already
	answered in this text?
A - Probably not, unless I'm in a very good mood.
Q - Will there be future versions of SOS?
A - Depends on my success at getting the "features to be added" to work and my will
	to work on it (writting SOS is not my obligation or job, ya know).
Q - What is the deal with the split mode stuff?
A - SOS does NOT fully adjust for split mode so it looks funky when you run it. This is
	harmless, but looks ugly. The best way to advoid this problem is to switch to
	"Full" mode before running SOS. If you do run SOS in split mode, you will have
	to change the mode back to spilt, exit the mode menu, then change the mode to
	full again after exiting SOS. This is necessary to make the TI-83 "realize"
	what mode it is in.
Q - Why is SOS started by a program called "A"?
A - This is to make SOS more accessable. It also saves two bytes (I like small).
* More will be added as I continue recieving questions!

>Concluding comments:
Thanks to everyone who gave me ideas!  There are too many to list here, but I'll
list a few of them:
	Hannes Edfeldt - gave me some helpful hints.
	Dan Englender - annoyed me into making SOS nicer.
	Bill Nagel - created AShell which is what SOS is modeled after.
	Tim Redmond - told me what was good/bad and gave me ideas.
	Matthew Shepcar - gave me some helpful hints.
	The makers of Fargo - came up with the design I tryied to impliment.

If you add my program to your page, please add a link to mine! :)
Visit my home page at:  http://www.usmo.com/~joewing/
Send comments/bugs to:  joewing@usmo.com

PLEASE DO NOT SEPARATE THIS DOCUMENT FROM SOS!!!

----> End of SOS.txt